GetNextEvent

GetNextEvent
Header:	Events.h		Carbon status:	Supported

Retrieves events one at a time from the Event Manager.

Boolean GetNextEvent (
    EventMask eventMask, 
    EventRecord *theEvent
);

eventMask: A value that indicates which kinds of events are to be returned; this parameter is interpreted as a sum of event mask constants. You specify the event mask using one or more of the values defined by the “EventMask Constant”. If no event of any of the designated types is available, GetNextEvent returns a null event.
theEvent: A pointer to an event structure for the next available event of the specified type or types. The GetNextEvent function removes the returned event from the event stream and returns the information about the event in an event structure. The event structure includes the type of event received and other information.

DISCUSSION

GetNextEvent returns false as its function result if the event being returned is a null event or if GetNextEvent has intercepted the event; otherwise, GetNextEvent returns true. The GetNextEvent function calls the Operating System Manager function SystemEvent to determine whether the event should be handled by the application or the Operating System.

Like WaitNextEvent, the GetNextEvent function calls SystemTask to give time to each open desk accessory or device driver to perform any periodic action defined for it. The GetNextEvent function also makes the alarm go off if the alarm is set and the current time is the alarm time. (The user sets the alarm using the Alarm Clock desk accessory.)

The GetNextEvent function also intercepts Command–Shift–number key sequences and calls the corresponding 'FKEY' resource to perform the associated action. The Event Manager’s processing of Command–Shift–number key sequences with numbers 3 through 9 can be disabled by setting the ScrDmpEnable global variable (a byte) to 0.

SPECIAL CONSIDERATIONS

For greater support of the multitasking environment, your application should use WaitNextEvent instead of GetNextEvent whenever possible. If your application does call GetNextEvent, it should also call the SystemTask function.

AVAILABILITY

Supported in Carbon. Available in Mac OS 8.1 and later when Carbon 1.0.2 or later is present.